##############################################################################
###+--------------+###########################################################
#+-| PROC_ENTRY() |------------------------------------+######################
#| +--------------+ Specifies procedure to be executed |######################
#|                  when key_sequence is activated     |######################
#+-----------------------------------------------------+######################
##############################################################################
##############################################################################
#+--| Summary |----------------+##############################################
#|     #INCLUDE system.hdr     |##############################################
#+-----------------------------+##############################################
##############################################################################
##############################################################################
#+--| Syntax |----------------------------------------------------+###########
#|     FUNCTION LOGICAL proc_entry PROTOTYPE                      |###########
#|      PARAMETERS UNTYPED hot_key, CONST CHAR key_sequence,;     |###########
#|          VALUE INT call_type                                   |###########
#+----------------------------------------------------------------+###########
##############################################################################
##############################################################################
#########+---| Description |----------------------------------------+#########
#########| The proc_entry() function specifies the procedure to be  |#########
#########| executed whenever key_sequence is activated.  hot_key    |#########
#########| can not be activated until the activate_procs or tsr     |#########
#########| procedure is issued.                                     |#########
#########| -------------------------------------------------------- |#########
#########| The procedure hot_key is any valid FORCE procedure.      |#########
#########| -------------------------------------------------------- |#########
#########| If proc_entry() returns FALSE, then it is unable to      |#########
#########| initialize the procedure hot_key as a resident           |#########
#########| procedure.  A common failure is due to an invalid        |#########
#########| key_sequence.                                            |#########
#########| -------------------------------------------------------- |#########
#########| call_type specifies when it is safe for proc_entry to be |#########
#########| invoked.  This is necessary to define because DOS could  |#########
#########| be in the middle of a disk operation when proc_entry is  |#########
#########| called.  If proc_entry also performs disk I/O, then DOS  |#########
#########| will be left in an unstable state.  Refer to DOS CALL    |#########
#########| TABLE to obtain the appropriate value of call_type for   |#########
#########| your program.                                            |#########
#########| -------------------------------------------------------- |#########
#########| key_sequence is a character string specifying the keys   |#########
#########| that activate the procedure hot_key.  It has the         |#########
#########| following format:                                        |#########
#########|                                                          |#########
#########|   "<key><key>...<key>"                                   |#########
#########|                                                          |#########
#########| The < and > characters are required.  Refer to TSR_HOT_  |#########
#########| KEYS_TABLE for valid character strings for <key>.        |#########
#########| -------------------------------------------------------- |#########
#########| A program may have several entry points, each            |#########
#########| initialized through the proc_entry() procedure.          |#########
#########| -------------------------------------------------------- |#########
#########| proc_entry() does NOT terminate the program.  The tsr    |#########
#########| procedure exits and makes the program resident.          |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Examples of several proc_entry() calls to           |#########
#########| *    demonstrate how to specify the key sequence.        |#########
#########|                                                          |#########
#########| proc_entry( proc1, "<Ctrl><E>" )                         |#########
#########| proc_entry( proc2, "<F10>" )                             |#########
#########| proc_entry( proc3, "<Leftshift><Ctrl><Alt><F>" )         |#########
#########| proc_entry( proc4, "<A>" )                               |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    The hot key procedure is executed whenever the      |#########
#########| *    user presses key_sequence.                          |#########
#########|                                                          |#########
#########| #include tsr.hdr                                         |#########
#########| PROCEDURE tsr_procedure                                  |#########
#########|     ? "You pressed <Ctrl><X> ! "                         |#########
#########| ENDPRO                                                   |#########
#########| PROCEDURE force_main                                     |#########
#########|     IF proc_entry( tsr_procedure,"<CTRL><X>" )           |#########
#########|         tsr()                                            |#########
#########|     ENDIF                                                |#########
#########|     ? "Unable to terminate."                             |#########
#########| ENDPRO                                                   |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 3 |-------------------------------------------+#########
#########| *    Have a user specify the key sequence.  (or ...have  |#########
#########| *    the keys specified in pick list.)                   |#########
#########|                                                          |#########
#########| ACCEPT "What hot keys? " TO the_keys                     |#########
#########| IF proc_entry( a_hot_key_proc, the_keys )                |#########
#########|     {...}                                                |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 4 |-------------------------------------------+#########
#########| *    A program can have multiple entry points.           |#########
#########|                                                          |#########
#########| PROCEDURE entry_one                                      |#########
#########|     ? "Executing entry point #1"                         |#########
#########|     ? "Activated by <Alt><F10>"                          |#########
#########| ENDPRO                                                   |#########
#########|                                                          |#########
#########| PROCEDURE entry_two                                      |#########
#########|     ? "Executing entry point #2"                         |#########
#########|     ? "Activated by <Leftshift><Q>"                      |#########
#########| ENDPRO                                                   |#########
#########|                                                          |#########
#########|     {...}                                                |#########
#########|     IF proc_entry( entry_one,"<ALT><F10>" ) .AND. ;      |#########
#########|        proc_entry( entry_two,"<Leftshift><Q> )           |#########
#########|         tsr( 16000 )                                     |#########
#########|     ENDIF                                                |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 5 |-------------------------------------------+#########
#########| *    A program can have internal "tsr" routines.         |#########
#########| *    Activate your "hot key" routines through the        |#########
#########| *    procedure activate_procs instead of tsr.  Your      |#########
#########| *    "hot key" procedures will be active, yet the        |#########
#########| *    program will NOT be TSR.                            |#########
#########|                                                          |#########
#########| PROCEDURE p1                                             |#########
#########|     {...}                                                |#########
#########| ENDPRO                                                   |#########
#########|                                                          |#########
#########|     IF proc_entry( pl,"<ALT><=>",&TSR_CALL_DOS )         |#########
#########|         activate_procs()                                 |#########
#########|     ENDIF                                                |#########
#########+----------------------------------------------------------+#########
##############################################################################